…, env design+plan

Snapshot of in-progress work before the engine-environments plan reshapes it:
- PkceAuthProvider per-env OAuth (with_environment/OAuthEnvironment) — to be
  replaced by the Environments resolver per the plan
- consistent outbound User-Agent (auto-wired from CliConfig; token traffic too)
- default 30s token-endpoint timeout + shared reqwest client
- design spec (docs/specs) and implementation plan (docs/plans)

Co-Authored-By: Claude Opus 4.8 <[email protected]>

… code

The CI Rust/Docs step runs `cargo doc` without features as well as with
`pkce-auth`. Two intra-doc links to `PkceAuthProvider::with_environments`
(in CliConfig and Environments docs) failed the no-feature build because the
`pkce` module is feature-gated (`no item named pkce in module auth`), and
`-D warnings` promotes broken-intra-doc-links to an error. Use plain code spans
referencing the `pkce-auth` feature instead.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

…fine)

Copilot review: the design spec and environments.md implied env-var-only
environments are resolvable/selectable, but resolve() treats an env as known
only if defined by a compiled default or environments.toml — env vars only
override fields of a defined env. Corrected the wording in both docs.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Copilot review round 2:
- tests/foundation.rs: the two execute_from tests reset the process-wide
  User-Agent at the end; a panicking assert would skip it and leak the
  derived UA into later tests. Replace the manual reset with a
  RestoreDefaultUserAgent RAII guard (drops while the UA lock is still held).
- src/environments.rs: document that Environments::resolve performs blocking
  filesystem I/O when the config-file layer is enabled, so it isn't called
  per-request from async handlers.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

…environment()

Copilot review round 3:
- Environments::list() swallows ANY file read/parse error, not just parse
  errors — corrected the doc comment.
- CommandContext::environment() can block on filesystem I/O via resolve();
  added a # Blocking note advising call-once-per-invocation.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Copilot review round 9: the implementation plan referenced internal
superpowers:* tool names that aren't actionable for repo readers. It was
one-off process scaffolding; remove it. The design spec (tool-agnostic) and the
durable user docs (docs/environments.md, docs/concepts.md) remain.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

…gn spec

Copilot review round 10:
- env set: give the `name` positional a value_name and help text, matching the
  config/auth built-in groups for consistent --help output.
- Remove the design spec: as a pre-implementation doc it had drifted from the
  shipped API (active_environment vs environment.active, &Environment vs owned,
  with_oauth vs with_client_id/...). The durable, accurate docs
  (docs/environments.md, docs/concepts.md) remain the source of truth.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

…tests

Copilot review round 11 flagged one more UA-mutating test lacking the panic-safe
guard. Rather than fix piecemeal, audited every test holding USER_AGENT_TEST_LOCK
and applied the RestoreDefaultUserAgent RAII guard (and an explicit cli/dev pin
where asserting the default) to all of them, so a panicking assertion can never
leak a mutated default UA into later tests in this binary.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Copilot review round 12: with no compiled or file-defined environments, the
unknown-env error rendered a dangling "known: ". Render "(none defined)" instead
(+ test).

Co-Authored-By: Claude Opus 4.8 <[email protected]>

get_credential_for resolved effective_scopes(env) up front on every credential
lookup, triggering an environments.toml read even when a cached token already
covers the required scopes. plan_step_up's coverage decision needs only
granted/required, so drop defaults from it (StepUp::Reauthenticate no longer
carries the union) and resolve per-env defaults only on the two paths that
actually re-authenticate. Hot path (cached token covers required) now does no
environment file I/O.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

Copilot review round 14: the doc said it only affected subsequently-created
HttpClients, but the default UA now also applies to the PKCE provider's
token/refresh requests and the client-credentials injector. Updated the doc.

Co-Authored-By: Claude Opus 4.8 <[email protected]>